<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
		<title>4.12.TransferView</title>
		<link type="text/css" rel="stylesheet" href="PLUGINS_ROOT/org.polarsys.capella.doc/html/styles.css"/>
	</head>
	<body>
		<h1 id="Transfer_View">Transfer View</h1>
		<p>Moving elements within the bounds of a single capella model is done via drag and drop in the capella project explorer. However, it is not possible to 
			drag an element out of a capella model and drop it into one of its referenced libraries. This is to prevent cycles in the project/library graph. It is however still possible to move elements from a capella model to a library with the help of a special tool, and that tool is called the 
			<i>Transfer View</i>. Before using the Transfer View, please read this documentation carefully.
		</p>
		<p>When the Transfer View (Window-&gt;Show View-&gt;Transfer) is opened for the first time, it looks like this:</p>
		<p>
			<img border="0" src="Images//9.5_MoveElementsView_1.png"/> 
		</p>
		<p>1. The Selection Area shows all elements that should be moved in 
			<b>bold</b>. Drag/Drop model elements from the Project Explorer over this area to fill the view. If the dropped element has children, the children will be moved together with the selected element. Another way to add elements to the Transfer View Selection Area is via the 
			<i>Send To Transfer View</i> context menu. To remove a selected element from the view, the 
			<i>Unstage Element</i> (
			<img height="20" width="21" border="0" src="Images//9.5_MoveElementsView_unstage.png"/>) action can be selected either via the context menu of the selection tree, or in the selection tree toolbar to the right side of the tree.
		</p>
		<p>2. The Destination Area shows the possible destinations for elements in the selection area. To set a new destination for a selected element, drag/drop the element from the selection area over a suitable parent in the destination area. Elements in the selection area for which a destination element has been selected will appear in green. To clear an already set destination for a selected element, use the 
			<i>Clear Parent</i> (
			<img height="20" width="21" border="0" src="Images//9.5_MoveElementsView_unstage.png"/>) action either via the Destination tree context menu, or the corresponding toolbar button to the right side of the tree.
		</p>
		<p>3. The execute button is initially disabled. As soon as a destination is set for 
			<b>all</b> selected elements, and no referential problems (see below) are detected, the execute button will be enabled. Selecting the button moves elements to their new destination and performs a semantic validation (see below). The move operation will be also be logged to the Capella information view (Window-&gt;Show View-&gt;Information). Note that the target library must be referenced in read/write mode by the project.
		</p>
		<p>4. The reset button will reset the view to its initial empty state.</p>
		<h3 id="Illegal_Backreferences">Illegal Backreferences</h3>
		<p>It is rarely ever possible to move an element in isolation. Usually, an element is part of a graph, connected to other elements that belong together: For example a Class B that extends another Class A cannot be moved without moving A too, since that would introduce a reference cycle between the source project and the target library. The Transfer View detects this and visualizes it as follows: When Class B is dropped onto the Selection Area, the Generalization child of A will be marked red. Hovering over the marked element will show additional informations about this 
			<i>illegal backreference</i>:
		</p>
		<p>
			<img height="300" width="1054" border="0" src="Images//9.5_MoveElementsView_2.png"/> 
		</p>
		<p>It is possible to click on the hyperlink in the tooltip to select the target element in the Capella project explorer. To ease navigation to problematic elements, the total number of problematic child elements is shown in red parentheses next to each element in the tree.</p>
		<p>As long as one or more backreferences are present, the execute button remains disabled. There are always multiple solutions to a backreference: In this example, either break the generalization, or add Class A to the selection area. The latter is done either via manual drag/drop, or by using one of the provided utility actions for backreference resolution:</p>
		<ul>
			<li>
				<i>Add referenced elements</i> (
				<img height="21" width="20" border="0" src="Images//9.5_MoveElementsView_addRequired.png"/>) adds direct backreferences for the selected element to the selection tree.
			</li>
			<li>
				<i>Add all referenced elements</i> (
				<img height="19" width="20" border="0" src="Images//9.5_MoveElementsView_addAllRequired.png"/>) adds direct backreferences for the selected element to the selection tree, and then recursively adds the backreferences for the added elements and so on. 
			</li>
		</ul>
		<p>Both actions can be invoked either from the context menu of a marked element, or via the corresponding toolbar buttons next to the selection tree.</p>
		<h3 id="Semantic_Validation">Semantic Validation</h3>
		<p>When the execute button is clicked, all selected elements are moved to their new destination, and a semantic validation is performed:</p>
		<ul>
			<li>Capella verifies that no illegal references between libraries are introduced by the operation.</li>
			<li>Capella verifies that existing references to and from moved elements are still valid. It is currently not possible to identify such a problem before the move is actually performed, which is why the validation must be performed only after the move completes.</li>
		</ul>
		<p>If no semantic validation problem is detected, the operation is finished, and the view resets to its initial empty state.</p>
		<p>Otherwise, semantic validation problems will be displayed in a dialog. The dialog offers to either abort the move, or to force it. The two options exist to overcome the following limitation: Semantic validation cannot distinguish between problems that are introduced by the move itself, and between problems that already existed before the move was initiated. Two examples are given to illustrate this:</p>
		<h3 id="Force_move_example">Force move example</h3>
		<p>Given is a Class A which has a Property which itself has a non-primitive Type T. This is not allowed in Capella. When A and T are moved to a library, the semantic validation dialog will open:</p>
		<p>
			<img height="230" width="518" border="0" src="Images//9.5_MoveElementsView_forceExample.png"/>
		</p>
		<p>Since the displayed problem existed beforehand and was not introduced by the move itself, it is fine to force the move in this case.</p>
		<h3 id="Cancel_move_example">Cancel move example</h3>
		<p>Given is a Logical Function F which is allocated by a LogicalComponent C. When F is moved to a Library, the semantic validation dialog will open:</p>
		<p>
			<img height="230" width="518" border="0" src="Images//9.5_MoveElementsView_cancelExample.png"/>
		</p>
		<p>It is not allowed that a Component allocates a Function that is in a Library. The problem was introduced by the move itself and didn't exist beforehand. Here, the correct decision would be to cancel the move.</p>
		<h3 id="Semantic_validation_best_practices">Semantic validation best practices</h3>
		<ul>
			<li>A good way to avoid validation problems that are unrelated to the move, like in the first example, is to make sure that no referential problems exist before the move is executed: Enable model validation rule I_38 and perform a validation on the entire capella model. If rule I_38 detects any problems that involves elements that are to be moved, such problems should be resolved before trying to execute a move, since it is very likely that the same problems will be displayed in the semantic validation dialog when the move is executed.</li>
		</ul>
		<ul>
			<li>If the semantic validation dialog opens, it is never wrong to cancel the move in order to to closely review the reported problems, as they are recorded also in the Capella information view (Window-&gt;Show View-&gt;Information). The state of the transfer view will be preserved, so it is possible to retry the move operation later.</li>
		</ul>
		<ul>
			<li>The Transfer View selection is linked to the Semantic Browser view (Window-&gt;Show View-&gt;Semantic Browser). Using both views in combination when planning a move operation will give a bigger picture of possible impacts.</li>
		</ul>
		<h3 id="Impacts_on_Diagrams">Impacts on Diagrams</h3>
		<p>Like any other model operation, moving elements can have an impact on existing Diagrams, both, in the source or the target project. Currently Capella has no tool to identify impacted diagrams. The semantic browser view (Window-&gt;Show View-&gt;Semantic Browser) can help with a manual impact analysis.</p>
		<h3 id="Example">Example</h3>
		<p>A step by step example is given to demonstrate the Transfer View workflow. The intention is to move the following elements to a library:</p>
		<p>
			<img border="0" src="Images//9.5_MoveElementsView_example1_1.png"/>
		</p>
		<p>Suppose these elements are in a project that references a library with read-write access policy.</p>
		<p>(For demonstration purposes, do not use the 
			<i>Send to Transfer View</i> action in this Example. Locate the elements in the Project Explorer instead. To see Parts and Functional Exchanges, deactivate the corresponding filters through the Project Explorer view menu.) 
		</p>
		<p>The first step is to drag elements from the Project Explorer and drop them onto the stage area on the left side of the Transfer view. To demonstrate the iterative workflow, start by adding only two Logical Components LC1 and LC2 to the stage area. The stage area will now look like this:</p>
		<p>
			<img border="0" src="Images//9.5_MoveElementsView_example1_2.png"/>
		</p>
		<p>Note there are some elements in red, and the execute button is not enabled. The project root element shows a red (4), indicating that there are 4 problems to resolve in total. An element in red is an element that still references elements in the project. Select the next red element either directly, or by clicking the small down arrow 
			<img border="0" src="Images//9.5_MoveElementsView_nextElement.png"/>. Hover over the element to trigger the tooltip that shows information about the problematic reference:
		</p>
		<p>
			<img border="0" src="Images//9.5_MoveElementsView_example1_3.png"/>
		</p>
		<p>A synthetic rule prevents moving a Component without moving its Part. Add the required element by clicking the 
			<i>Add referenced elements</i> action (
			<img height="21" width="20" border="0" src="Images//9.5_MoveElementsView_addRequired.png"/>), or via the context menu. After performing the same step for the other Component, the view looks like this:
		</p>
		<p>
			<img border="0" src="Images//9.5_MoveElementsView_example1_4.png"/>
		</p>
		<p>Still, there are 2 elements with backreferences: Each component allocates a function, so we must add the functions too:</p>
		<p>
			<img border="0" src="Images//9.5_MoveElementsView_example1_5.png"/>
		</p>
		<p>Select the two Component Functional Allocation elements and use the 
			<i>Add referenced elements</i> action to add the functions:
		</p>
		<p>
			<img border="0" src="Images//9.5_MoveElementsView_example1_6.png"/>
		</p>
		<p>No red elements are left. Now select the new parents for each 
			<b>bold</b> element in the staging area. Drag the Components and Part elements to the right area that shows the library, and drop them onto the Root Logical Component. Do the same for the the Function elements, this time using the Root Logical Function as the new parent:
		</p>
		<p>
			<img border="0" src="Images//9.5_MoveElementsView_example1_7.png"/>
		</p>
		<p>All 
			<b>bold</b> elements have become green, which indicates that a new parent was chosen for each of the elements. The execute button in the view toolbar is now enabled. Click it. Semantic validation will report an error:
		</p>
		<p>
			<img border="0" src="Images//9.5_MoveElementsView_example1_8.png"/>
		</p>
		<p>It is not possible to leave the Functional Exchange element in the project. It must be moved too. Cancel the operation, and add the Functional Exchange:</p>
		<p>
			<img border="0" src="Images//9.5_MoveElementsView_example1_9.png"/>
		</p>
		<p>The Functional Exchange has references to 2 Exchange Items. Add the Exchange Items by using the 
			<i>Add referenced elements</i> action.
		</p>
		<p>
			<img border="0" src="Images//9.5_MoveElementsView_example1_10.png"/>
		</p>
		<p>Selecting the 
			<i>Next/Previous element</i> actions with the Ctrl-Key pressed will skip over 
			<i>green</i> elements. Use this as a shortcut to find the next element that needs to be worked on. Drop the Functional Exchange onto the Root Logical Function, and the Exchange Items onto the Logical Data Package:
		</p>
		<p>
			<img border="0" src="Images//9.5_MoveElementsView_example1_11.png"/>
		</p>
		<p>The execute button is again enabled. Select it to execute the move. This time, the operation is successful. Open the Information View to inspect the generated log entries:</p>
		<p>
			<img border="0" src="Images//9.5_MoveElementsView_example1_12.png"/>
		</p>
		<p>This concludes the example.</p>
	</body>
</html>